feat(go): Phase A — MCP boot (handshake + tools/list + 8 stub tools)#86
Merged
couragehong merged 6 commits intoyg/go-runed-migrationfrom Apr 27, 2026
Merged
feat(go): Phase A — MCP boot (handshake + tools/list + 8 stub tools)#86couragehong merged 6 commits intoyg/go-runed-migrationfrom
couragehong merged 6 commits intoyg/go-runed-migrationfrom
Conversation
cmd/rune-mcp/main.go: MCP server bootstrap (NewServer + Register +
StdioTransport.Run). Empty Deps, no boot loop / config.Load yet.
isNormalShutdown() drops exit 1 for stdin EOF · ctx cancel ·
jsonrpc2.ErrServerClosing (internal SDK error, matched by message).
internal/mcp/tools.go: Register binds all 8 tools via stubHandler[In, Out].
Input/output schema auto-inferred; tools/call returns IsError
"not yet implemented (skeleton phase A)". Phase 5 swaps the stub for
service-layer wrappers.
go.mod/go.sum: modelcontextprotocol/go-sdk v1.5.0 (D2). Go 1.24 → 1.25
per SDK requirement.
.gitignore: bin/ + *.test + coverage.out.
Smoke tests:
./bin/rune-mcp < /dev/null → exit 0
echo '{"method":"initialize",...}' | ./bin/rune-mcp
→ {"result":{"serverInfo":{"name":"rune-mcp","version":"0.4.0-alpha"},
"capabilities":{"tools":{"listChanged":true},...}}}, exit 0
다음: ~/.claude/mcp.json에 별도 entry로 등록 → Claude Code에서 8개 tool 인식 확인.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
새 디렉토리 docs/v04/progress/ 신설 — spec(How)·overview(Why)·notes (검증 로그)와 별개로 "실제 구현이 어디까지 동작하는가 + 어떻게 직접 검증하는가"를 vertical slice 단위로 추적. phase-a-mcp-boot.md (직전 커밋 19b7bf6과 한 쌍): - 동작하는 기능 6가지 (빌드 · initialize · tools/list · schema 자동 추론 · tools/call stub · 정상 종료) - 동작하지 않는 것 (Phase A 한계 표 — Vault·envector·embedder·service 레이어 전부 미구현) - 확인법 3 레벨: CLI 직접 / Claude Code 등록 / MCP Inspector 각 레벨마다 step + 기대 출력 + 합격 기준 - Troubleshooting + 코드 변경 요약 + 다음 마일스톤 후보 progress/README.md (인덱스): - 디렉토리 목적 · spec/notes와의 차이 - 문서 명명 규칙 + "Phase A vs Phase 1~7" 관계 - 현재까지 추적된 마일스톤 표 (Phase A only) + 예정 마일스톤 docs/v04/README.md: 디렉토리 구조 표에 progress/ + notes/flow-matrix.md 한 줄씩 추가. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
기존 §3 (Level 1·2·3 합격 시퀀스)는 한 번 통과를 위한 step. 그 위에
§4를 신설해 반복 작업 시 그대로 복붙해 쓰는 명령어 모음을 정리.
Phase B / Phase 4 / Phase 5 에서도 같은 회로 재사용 가능.
§4 구성:
- 4.1 서버 실행 4가지 변형 (foreground · stdin EOF · stderr 분리 · Inspector)
- 4.2 단발 JSON-RPC 요청 패턴 + MCP framing 3 규칙
(initialize → notifications/initialized → tools/* 순서, newline framing,
마지막 sleep 0.3-0.5s 권장)
- 4.3 8 tool 각각 minimum 인자 호출 cookbook
- 4.4 mcp_call bash 헬퍼 (8 tool 검증 후 채택). default `{}` expansion 함정
(`${2:-{}}`)도 명시
- 4.5 jq 응답 분석 패턴 7가지 (이름 / schema / required 매트릭스 / text 등)
- 4.6 디버깅 (stderr 분리, raw dump, tee로 input/output 동시 저장)
- 4.7 양방향 stateful 세션 (bash coproc) — 옵션
- 4.8 ~/.claude/mcp.json 등록 후 검증 명령어
§0 메타데이터 박스에 §4 navigation 한 줄 추가.
번호 시프트: 기존 §4 Troubleshooting → §5, §5 코드 변경 → §6, §6 다음 마일스톤 → §7.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
couragehong
force-pushed
the
yg/first-mcp-boot
branch
from
44d8299 to
8574aa5
Compare
esifea
reviewed
Apr 27, 2026
esifea
reviewed
Apr 27, 2026
Reviewer A (Go 코드 품질) Critical 2 + Major 다수: - isNormalShutdown dead branch 제거 (nil || ctx.Canceled 만) - stubHandler 가 *Deps 캡처 (8 call site 시그니처 통일) - Register 가 error 반환 + defer recover() (AddTool panic 가드) - log.Printf → slog.Error - go.mod toolchain go1.25.0 directive - Deps ghost field 제거 → 빈 struct + 향후 sketch 코멘트 Reviewer B (설계/문서) Major 8 — doc 정확도: - LOC 정정 (main.go 80→74, tools.go 137→134) - §1.5 code block runnable + topk non-nullable 정정 - §2.2 absolute path placeholder + namespace 충돌 설명 - §4.7 macOS bash 3.2 coproc 경고 - §7 다음 마일스톤 11개로 확장 phase-a-mcp-boot.md 슬림화 (588→180줄): - F1~F6 narrative → 동작/한계 매트릭스 - §3 Level 1.1~1.6 6 시퀀스 → 핵심 3 블록 (build/list/call) - §4 cookbook 8 subsection → mcp_call 헬퍼 + 8 tool 호출 1 블록 - §6 코드 변경 요약 삭제 (git diff에 있음) 검증: go build · go vet · smoke test (initialize → tools/list 8 → tools/call) ✅ Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
couragehong
force-pushed
the
yg/first-mcp-boot
branch
from
8574aa5 to
e042ab3
Compare
Contributor
✅ All tests passed
Full Test Results366 passed, 0 failed, 2 skipped (368 total) — See CI logs
|
esifea
reviewed
Apr 27, 2026
esifea
reviewed
Apr 27, 2026
esifea
approved these changes
Apr 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What changed:
cmd/rune-mcp/main.go— MCP server bootstrap (NewServer + Register + StdioTransport.Run).isNormalShutdown()는nil || errors.Is(err, context.Canceled)두 조건만 처리 — stdin EOF 는 SDKConnection.Wait가 내부적으로 nil 로 필터링하므로 여기 도달하지 않고, ctx 취소(SIGINT/SIGTERM)는context.Canceled로 surface.internal/mcp/tools.go— 8개 tool 을stubHandler[In, Out]로 등록. SDK 가 input/output Go struct 에서 JSON schema 자동 추론.tools/call은IsError "<tool> is not yet implemented (skeleton phase A — MCP handshake + tools/list only)"반환.go.mod—modelcontextprotocol/go-sdk v1.5.0추가, Go 1.24 → 1.25 directive (SDK 요구).stubHandler가*Deps캡처(8 call site 시그니처 통일),Register가error반환 +defer recover()(첫 panic 잡고 즉시 return — misconfigured tool 을 startup error 로 surface),log.Printf→slog.Error, dead branch 제거.docs/v04/progress/— Phase A 기능·한계·검증법 (CLI / Claude Code 등록 / MCP Inspector 3 레벨), §4 명령어 cookbook (mcp_call bash 헬퍼 + jq 분석 패턴).Why: v0.4 Go 마이그레이션의 첫 vertical slice — MCP handshake 와 tool discovery 가 실제로 동작하는지 end-to-end 로 확인하기 위함. 후속 Phase B~7 에서 stub 을 service 레이어로 교체할 때 회로(빌드·등록·검증)를 재사용할 수 있도록 cookbook 을 함께 정리.
Scope:
initialize→notifications/initialized→tools/list핸드셰이크 (capabilities: {logging:{}, tools:{listChanged:true}})rune_capture/rune_recall/rune_capture_history/rune_delete_capture/rune_vault_status/rune_diagnostics/rune_reload_pipelines/rune_batch_capturetools/callstub 응답 (IsError:true) + 정상 종료 (exit 0)